import Example from '~/components/example'
import { Code, InlineCode } from '~/components/text/code'
import Link from '~/components/text/link'
import {
  InputTable,
  OutputTable,
  Row,
  Cell,
  TypeCell,
  BoldCell,
  BooleanCell
} from '~/components/api/table'
import Endpoint from '~/components/api/endpoint'
import Request from '~/components/api/request'

export const meta = {
  editUrl: 'pages/docs/api/v1/api-docs-mdx/endpoints/teams.mdx',
  lastEdited: '2019-08-27T22:49:42.000Z'
}

## Teams

### Create a team

<Endpoint method="POST" url="/teams" />

Create a new team under your account. You need to send a `POST` request with the desired team slug.

#### Input

<InputTable>
  <Row>
    <BoldCell>slug</BoldCell>
    <TypeCell>String</TypeCell>
    <BooleanCell status={true} />
    <Cell>The desired slug for the team.</Cell>
  </Row>
</InputTable>

<Example>
  Example request:

<Request
  method="POST"
  url="https://api.zeit.co/teams"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`,
    'Content-Type': 'application/json'
  }}
  body={{
    slug: 'a-random-team'
  }}
/>

Example response:

<Code lang="json">{`{
    "id": "team_LLHUOMOoDlqOp8wPE4kFo9pE"
  }`}</Code>
</Example>

### Delete a Team

<Endpoint method="DELETE" url="/v1/teams/:id" />

Delete a team under your account. You need to send a `DELETE` request with the desired team `id`.

#### Input

<InputTable>
  <Row>
    <BoldCell>id</BoldCell>
    <TypeCell>String</TypeCell>
    <BooleanCell status={true} />
    <Cell>The desired id for the team.</Cell>
  </Row>
</InputTable>

<Example>
  <span>Example request:</span>

<Request
  method="DELETE"
  url="https://api.zeit.co/v1/teams/team_LLHUOMOoDlqOp8wPE4kFo9pE"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
/>

Example response:

<Code lang="json">{`{
  "id": "team_LLHUOMOoDlqOp8wPE4kFo9pE"
}`}</Code>
</Example>

### List all your teams

<Endpoint method="GET" url="/teams" />

Get a list of all the team you belong to.

#### Output

<OutputTable>
  <Row>
    <BoldCell>teams</BoldCell>
    <TypeCell>List</TypeCell>
    <Cell>
      The list of each team member as described on{' '}
      <Link href="#endpoints/teams/get-single-team-information">
        Get single team information
      </Link>
      .
    </Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  url="https://api.zeit.co/teams"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example response:

<Code lang="json">{`{
    "teams": [
      {
        "id": "team_ofwUZockJlL53hINUGCc1ONW",
        "slug": "my-team",
        "name": "My Team",
        "creatorId": "2qDDuGFTWXBLDNnqZfWPDp1A",
        "created": "2017-04-29T17:21:54.514Z",
        "avatar": null
      }
    ]
  }`}</Code>
</Example>

### Get single team information

<Endpoint>
  GET /teams/:id
  <br />
  GET /teams?slug
</Endpoint>

Get the information of a specific team, it could be used either passing the `:id` in the URL or the team `slug` as a query parameter.

#### Output

<OutputTable>
  <Row>
    <BoldCell>id</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>
      The team unique identifier. Always prepended by{' '}
      <InlineCode>team_</InlineCode>.
    </Cell>
  </Row>
  <Row>
    <BoldCell>slug</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>
      The team slug. A slugified version of the <InlineCode>name</InlineCode>.
    </Cell>
  </Row>
  <Row>
    <BoldCell>name</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>The name of the team.</Cell>
  </Row>
  <Row>
    <BoldCell>creatorId</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The ID of the user who created the team.</Cell>
  </Row>
  <Row>
    <BoldCell>avatar</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell />
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  url="https://api.zeit.co/teams/team_ofwUZockJlL53hINUGCc1ONW"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example response:

<Code lang="json">{`{
    "id": "team_ofwUZockJlL53hINUGCc1ONW",
    "slug": "my-team",
    "name": "My Team",
    "creatorId": "2qDDuGFTWXBLDNnqZfWPDp1A",
    "created": "2017-04-29T17:21:54.514Z",
    "avatar": null
  }`}</Code>
</Example>

### Update team information

<Endpoint method="PATCH" url="/teams/:id" />

Update the information of the team defined with the id. You need to send a `PATCH` request with a body containing the information you want to change.

> **Note**: You need to be `OWNER` to use it.

#### Input

<InputTable>
  <Row>
    <BoldCell>slug</BoldCell>
    <TypeCell>String</TypeCell>
    <BooleanCell status={false} />
    <Cell>The new team slug.</Cell>
  </Row>
  <Row>
    <BoldCell>name</BoldCell>
    <TypeCell>String</TypeCell>
    <BooleanCell status={false} />
    <Cell>The new team name.</Cell>
  </Row>
</InputTable>

<Example>
  Example request:

<Request
  method="PATCH"
  url="https://api.zeit.co/teams/team_ofwUZockJlL53hINUGCc1ONW"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`,
    'Content-Type': 'application/json'
  }}
  body={{
    name: 'My Cool Team'
  }}
/>

Example response:

<Code lang="json">{`{
    "id": "team_ofwUZockJlL53hINUGCc1ONW",
    "slug": "my-team",
    "name": "My Cool Team",
    "creator_id": "2qDDuGFTWXBLDNnqZfWPDp1A",
    "creatorId": "2qDDuGFTWXBLDNnqZfWPDp1A"
  }`}</Code>
</Example>

### Get list of team members

<Endpoint method="GET" url="/teams/:id/members" />

Get the list of team members of the team defined in the URL. The response is a list of maps with the following format.

#### Output

<OutputTable>
  <Row>
    <BoldCell>uid</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The team member unique identifier.</Cell>
  </Row>
  <Row>
    <BoldCell>role</BoldCell>
    <TypeCell>Enum</TypeCell>
    <Cell>
      The role inside the team, it could be <InlineCode>OWNER</InlineCode> or{' '}
      <InlineCode>MEMBER</InlineCode>.
    </Cell>
  </Row>
  <Row>
    <BoldCell>email</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>The email address of the team member.</Cell>
  </Row>
  <Row>
    <BoldCell>username</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>The username of the team member.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  url="https://api.zeit.co/teams/team_ofwUZockJlL53hINUGCc1ONW/members"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example response:

<Code lang="json">{`[
    {
      "uid": "2qDDuGFTWXBLDNnqZfWPDp1A",
      "role": "OWNER",
      "email": "user-emailgmail.com",
      "username": "some-user"
    },
    {
      "uid": "JJHkdv6NaPOTH88pXn8FEuGz",
      "role": "OWNER",
      "email": "another-user@mail.com",
      "username": "another-user"
    }
  ]`}</Code>
</Example>

### Invite user to team

<Endpoint method="POST" url="/teams/:id/members" />

Invite a user to join the team specified in the URL. To use it send a `POST` request with the user email in the body.

> **Note**: You need to be `OWNER` to use it.

#### Input

<InputTable>
  <Row>
    <BoldCell>email</BoldCell>
    <TypeCell>String</TypeCell>
    <BooleanCell status={true} />
    <Cell>The email address of the user to invite.</Cell>
  </Row>
</InputTable>

#### Output

<OutputTable>
  <Row>
    <BoldCell>uid</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The ID of the invited user.</Cell>
  </Row>
  <Row>
    <BoldCell>username</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>The username of the invited user.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  method="POST"
  url="https://api.zeit.co/teams/team_ofwUZockJlL53hINUGCc1ONW/members"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`,
    'Content-Type': 'application/json'
  }}
  body={{
    email: 'user@mail.com'
  }}
/>

Example response:

<Code lang="json">{`{
    "uid": "kr1PsOIzqEL5Xg6M4VZcZosf",
    "username": "an-user"
  }`}</Code>
</Example>

### Change user role

<Endpoint method="PATCH" url="/teams/:id/members/:userId" />

Change the role of an user inside a team member. To change it send a `PATCH` request, if the change is done you will receive a 200 status code with an empty body.

> **Note**: You need to be `OWNER` to use it.

#### Input

<InputTable>
  <Row>
    <BoldCell>role</BoldCell>
    <TypeCell>Enum</TypeCell>
    <BooleanCell status={true} />
    <Cell>
      The new role of the team member, it could be{' '}
      <InlineCode>OWNER</InlineCode> or <InlineCode>MEMBER</InlineCode>.
    </Cell>
  </Row>
</InputTable>

<Example>
  Example request:

<Request
    method="PATCH"
    url="https://api.zeit.co/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf"
    headers={{
      Authorization: `Bearer ${(props.testingToken ? props.testingToken.token : '$TOKEN')}`,
      'Content-Type': 'application/json'
    }}
    body={{
      "role": "OWNER"
    }}
  />
</Example>

### Remove user from team

<Endpoint method="DELETE" url="/teams/:id/members/:userId" />

Remove the specified user from a team.

> **Note**: You need to be `OWNER` to use it and the user **must not** be an owner themselves.

<Example>
  Example request:

<Request
    method="DELETE"
    url="https://api.zeit.co/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf"
    headers={{
      Authorization: `Bearer ${(props.testingToken ? props.testingToken.token : '$TOKEN')}`
    }}
  />
</Example>
